我們用 SMART——Specific（具體）、Measurable（可衡量）、Achievable（可達成）、Relevant（具關聯）、Time-bound（有時限）——把每個故事拆成五天，作為每次動手造輪子前的五個檢查問題。

本篇是故事五「擔心客戶看不懂 OpenAPI 文件，我急到沒看到 Postman，先刻了一個範例 App」的 Specific 篇：現在真正要解決的是什麼問題？

本篇定位：故事五的開場，還原一句模糊的「不會用」如何在被拆開之前，先被翻譯成一個開發需求。

當時發生了什麼

事情的起點是一封轉述。業務端傳回來一句話：「客戶說 API 不會用。」

我們手上有一份 OpenAPI 規格（OpenAPI Specification，以 YAML 或 JSON 描述 API 契約的格式），也有一個由它渲染出來的 Swagger UI 頁面，端點、參數、回應結構都在上面。所以那句話落進會議室的時候，第一個反應不是疑問，是慚愧：文件明明有，客戶還是不會用，那一定是文件不夠親切。

接下來的推論鏈條走得很快，中間幾乎沒有停頓：文件不夠親切，就要更直覺；更直覺，就要有畫面；有畫面，就是做一個範例 App。散會之前，前端框架已經選好了，有人開始畫登入頁。我那時很有幹勁，覺得這是難得能替客戶著想的一次。

兩週後，App 跑起來了：可以登入、填表單、看到回應。示範那天客戶的確點了頭，但會議尾聲有人補了一句：「其實我們工程師是卡在認證那一關，一直拿到 401。」那是整份文件裡最短的一段：存取權杖（token）該怎麼帶。我們花兩週做出來的東西，和那句「不會用」之間，可能一次也沒對上過。

真正的問題在哪裡

「不會用」是症狀，不是需求。它底下藏著好幾種完全不同的阻礙，每一種的解法成本差了一個數量級。

第一種是不知道端點與參數。這是文件問題，補齊 OpenAPI 的欄位說明與範例值就好。

第二種是認證卡關，也最常被文件一筆帶過，因為對寫 API 的人來說它太理所當然。API key 要放進哪個標頭、名稱寫什麼；存取權杖的正確寫法是 Authorization: Bearer <token>，最常見的錯誤是漏掉 Bearer 這個前綴，只把權杖本身貼上去；至於把權杖塞進 query string，RFC 6750 已經列為 SHOULD NOT，OAuth 2.0 安全最佳實務 RFC 9700 更進一步規定 MUST NOT。而如果走的是 OAuth 2.0，第一步還不是呼叫業務端點，是先向 token endpoint 換取存取權杖。這幾行沒寫進文件，客戶就只能猜。

第三種是不知道呼叫順序：哪個請求要先發、拿到的 ID 要餵給誰。這是流程問題，需要一段敘述，一份端點清單填不了。

另外兩種是錯誤訊息讀不懂——只看到 400，不知道是缺欄位還是格式錯——以及使用者不是工程師、每天要重複跑固定流程，這才是唯一可能需要圖形介面的情況。

我們沒有問是哪一種，就直接跳到最後一種去解。而且是替別人跳的。前四次動手，改造的都是讓自己不安心的那一塊——有時候是因為不熟，有時候是因為太熟；這一次我對自己的 API 沒有不安，不安的是「客戶可能不懂」——而那份不安沒有任何人證實過。

這種錯位披著體貼的外衣，特別難察覺：前四次多少還有人問過「這是不是做太多了」，這一次沒有人問，因為所有人都覺得是在服務客戶。沒問過卡點的體貼還是猜測，只是這次的成本由客戶一起承擔。

而且那個 App 不在需求清單上，沒有驗收條件，也沒人指定誰維護。

可以怎麼做

Specific 這一步要做的事，是把轉述換成第一手觀察。

先把「不會用」還原成一個可觀察的使用任務：「誰，在什麼環境，想完成什麼，卡在哪一個步驟，看到什麼訊息。」例如「客戶的後端工程師，在測試環境，想取得一筆訂單資料，帶了 API key 卻收到 401，不確定該放哪個標頭」。能填滿這句話，解法通常自己就浮出來了；填不滿，代表我們手上只有傳聞。

而最快的填法不是開會，是請對方把實際發出的請求與收到的回應貼過來，遮掉機密資訊即可。一則 curl 指令加一段回應內容，勝過三輪轉述。

接著分清楚三種東西不要互相取代：開發者文件回答「有什麼、怎麼呼叫」；測試工具（Swagger UI 的 Try it out、Postman、curl）回答「我現在試一次看看」；正式產品介面回答「我每天要用這個做事」。客戶說不會用時，缺的絕大多數是前兩種。用第三種去補前兩種，除了貴，還會讓缺口留在原地：文件錯的地方，做了 App 還是錯的，只是被我們自己的程式掩蓋了。

最後盤點使用者：誰會呼叫這組 API、是工程師還是操作人員、一次性串接還是長期營運。答案直接決定支援方式：整合期的工程師要的是可執行的請求範例，每天跑固定流程的操作人員才可能需要介面。

今天學到的事

客戶說不會用，不代表答案一定是一套 App；有時候他只是缺一個可以直接按下 Send 的請求範例。差別在於有沒有先把一句轉述換成一個具體卡點。

我也學到「體貼」最容易夾帶範圍。前幾個故事讓範圍失守的是「順便」，這次是「客戶應該會需要」——不需要客戶開口，也不需要任何人核准，就能長出一個沒人下訂單的產品。

方向就算抓對了，還有一個問題沒解決：怎麼知道客戶真的會用了？他那天是點了頭，可是點頭不是證據。那該拿什麼當證據？